MkConfigSetting

Show source on GitHub

Node for describing a config setting.

ExamplesDocStringsBase classes⋔ Inheritance diagramNodeFileCode

Example: YAML format

Jinja

{{ "path" | MkConfigSetting(mode="yaml",
                            setting={"plugins": {"mknodes": {"path": "path.to.module"}}},
                            description="Some **markdown** to describe the setting",
                            default="path.to.module")}}

Python

MkConfigSetting(
    "path",
    "Some **markdown** to describe the setting",
    setting={"plugins": {"mknodes": {"path": "path.to.module"}}},
    default="path.to.module",
    mode="yaml",
)

RenderedMarkdownHtmlRepr tree

**path**

Default: 'path.to.module'

Some markdown to describe the setting

plugins:
  mknodes:
    path: path.to.module

`**path**`
:   Default: `'path.to.module'`

    Some **markdown** to describe the setting


    ```` {.yaml }
    plugins:
      mknodes:
        path: path.to.module

    ````

<p><code>**path**</code>
:   Default: <code>'path.to.module'</code></p>
<div class="language-text highlight"><pre><span></span><code>Some **markdown** to describe the setting


```` {.yaml }
plugins:
  mknodes:
    path: path.to.module

````
</code></pre></div>

MkConfigSetting
╰── MkCode('plugins:\n  mknodes:\n    path: path.to.module\n', language='yaml')
    ╰── MkText('plugins:\n  mknodes:\n    path: path.to.module\n')

Example: JSON format

Jinja

{{ "path" | MkConfigSetting(mode="json",
                            setting={"plugins": {"mknodes": {"path": "path.to.module"}}},
                            description="Some **markdown** to describe the setting",
                            default="path.to.module")}}

Python

MkConfigSetting(
    "path",
    "Some **markdown** to describe the setting",
    setting={"plugins": {"mknodes": {"path": "path.to.module"}}},
    default="path.to.module",
    mode="json",
)

RenderedMarkdownHtmlRepr tree

**path**

Default: 'path.to.module'

Some markdown to describe the setting

{
    "plugins": {
        "mknodes": {
            "path": "path.to.module"
        }
    }
}

`**path**`
:   Default: `'path.to.module'`

    Some **markdown** to describe the setting


    ```` {.json }
    {
        "plugins": {
            "mknodes": {
                "path": "path.to.module"
            }
        }
    }
    ````

<p><code>**path**</code>
:   Default: <code>'path.to.module'</code></p>
<div class="language-text highlight"><pre><span></span><code>Some **markdown** to describe the setting


```` {.json }
{
    &quot;plugins&quot;: {
        &quot;mknodes&quot;: {
            &quot;path&quot;: &quot;path.to.module&quot;
        }
    }
}
````
</code></pre></div>

MkConfigSetting
╰── MkCode('{\n    "plugins": {\n        "mknodes": {\n    ...   "path": "path.to.module"\n        }\n    }\n}', language='json')
    ╰── MkText('{\n    "plugins": {\n        "mknodes": {\n            "path": "path.to.module"\n        }\n    }\n}')

Example: TOML format

Jinja

{{ "path" | MkConfigSetting(mode="toml",
                            setting={"plugins": {"mknodes": {"path": "path.to.module"}}},
                            description="Some **markdown** to describe the setting",
                            default="path.to.module")}}

Python

MkConfigSetting(
    "path",
    "Some **markdown** to describe the setting",
    setting={"plugins": {"mknodes": {"path": "path.to.module"}}},
    default="path.to.module",
    mode="toml",
)

RenderedMarkdownHtmlRepr tree

**path**

Default: 'path.to.module'

Some markdown to describe the setting

[plugins.mknodes]
path = "path.to.module"

`**path**`
:   Default: `'path.to.module'`

    Some **markdown** to describe the setting


    ```` {.toml }
    [plugins.mknodes]
    path = "path.to.module"

    ````

<p><code>**path**</code>
:   Default: <code>'path.to.module'</code></p>
<div class="language-text highlight"><pre><span></span><code>Some **markdown** to describe the setting


```` {.toml }
[plugins.mknodes]
path = &quot;path.to.module&quot;

````
</code></pre></div>

MkConfigSetting
╰── MkCode('[plugins.mknodes]\npath = "path.to.module"\n', language='toml')
    ╰── MkText('[plugins.mknodes]\npath = "path.to.module"\n')

Bases: MkTemplate

__init__

__init__(
    title: str,
    description: str,
    *,
    setting: dict[str, Any] | str | None = None,
    default: str | int | None = None,
    version_added: str | None = None,
    optional: bool | None = None,
    mode: superdict.MarkupTypeStr | None = None,
    **kwargs: Any
)

Parameters:

Name	Type	Description	Default
title	str	Setting title	required
description	str	Setting description	required
setting	dict[str, Any] | str | None	(Nested) json-like object representing the setting	None
default	str | int | None	Default setting value	None
version_added	str | None	Version added	None
optional	bool | None	Whether setting is optional. (None hides the label)	None
mode	MarkupTypeStr | None	Markup language of settings file	None
kwargs	Any	Keyword arguments passed to parent	{}

Name	Children	Inherits
MkTemplate mknodes.templatenodes.mktemplate Node representing a jinja template.	MkCliDoc MkMaterialBadge MkImageCompare MkImageSlideshow MkIFrame MkCard MkInstallGuide MkCodeOfConduct MkCommitConventions MkPullRequestGuidelines MkDevEnvSetup ...	MkContainer

graph TD
  94854583234560["mkconfigsetting.MkConfigSetting"]
  94854582782240["mktemplate.MkTemplate"]
  94854582919984["mkcontainer.MkContainer"]
  94854582916880["mknode.MkNode"]
  94854582838576["node.Node"]
  140544995341632["builtins.object"]
  94854582782240 --> 94854583234560
  94854582919984 --> 94854582782240
  94854582916880 --> 94854582919984
  94854582838576 --> 94854582916880
  140544995341632 --> 94854582838576

/home/runner/work/mknodes/mknodes/mknodes/templatenodes/mkconfigsetting/metadata.toml

[metadata]
name = "MkConfigSetting"
icon = "mdi:library"
virtual_children = true

[requirements.extension.def_list]

[examples.yaml]
title = "YAML format"
jinja = """
{{ "path" | MkConfigSetting(mode="yaml",
                            setting={"plugins": {"mknodes": {"path": "path.to.module"}}},
                            description="Some **markdown** to describe the setting",
                            default="path.to.module")}}
"""

[examples.json]
title = "JSON format"
jinja = """
{{ "path" | MkConfigSetting(mode="json",
                            setting={"plugins": {"mknodes": {"path": "path.to.module"}}},
                            description="Some **markdown** to describe the setting",
                            default="path.to.module")}}
"""

[examples.toml]
title = "TOML format"
jinja = """
{{ "path" | MkConfigSetting(mode="toml",
                            setting={"plugins": {"mknodes": {"path": "path.to.module"}}},
                            description="Some **markdown** to describe the setting",
                            default="path.to.module")}}
"""

[output.markdown]
template = """
{{ node.title | md_style(bold=True, code=True) }}
:   {% filter indent %}Default: `{{ node.default | repr }}`

{% if node.version_added %}
Version added: `{{ node.version_added }}`

{% endif %}
{% if node.optional is not none %}
Required: `{{ "yes" if node.required else "no" }}`

{% endif %}
{{ node.description }}


{% if node.setting is instance(dict) %}
{{ node.setting | serialize(node.mode) | MkCode(language=node.mode) }}
{% else %}
{{ node.setting | MkCode(language=node.mode) }}
{% endif %}
{% endfilter %}
"""

class MkConfigSetting(mktemplate.MkTemplate):
    """Node for describing a config setting."""

    ICON = "material/library"

    def __init__(
        self,
        title: str,
        description: str,
        *,
        setting: dict[str, Any] | str | None = None,
        default: str | int | None = None,
        version_added: str | None = None,
        optional: bool | None = None,
        mode: superdict.MarkupTypeStr | None = None,
        **kwargs: Any,
    ):
        """Constructor.

        Arguments:
            title: Setting title
            description: Setting description
            setting: (Nested) json-like object representing the setting
            default: Default setting value
            version_added: Version added
            optional: Whether setting is optional. (None hides the label)
            mode: Markup language of settings file
            kwargs: Keyword arguments passed to parent
        """
        super().__init__("output/markdown/template", **kwargs)
        self.title = title
        self.setting = setting
        self.default = default
        self.version_added = version_added
        self.description = description
        self.optional = optional
        self.mode = mode